Command

New in version 2.2.

Starting in v2.2, pydicom offers a useful command-line interface (CLI) for exploring DICOM files, and access to the codify option for creating pydicom Python code. Additional subcommands may be added over time.

Example at the command line in a terminal window:

Note that prefixing the file specification with pydicom:: will read the file from the pydicom test data files rather than from the normal file system. The following examples will use that so that you can replicate these examples exactly. In normal use, you would leave the pydicom:: prefix off when working with your files.

You can also show just parts of the DICOM file by specifying a data element using the usual pydicom keyword notation:

You can see the available subcommands by simply typing pydicom with no arguments, or with pydicom help:

And, as noted in the block above, you get help for a particular subcommand by typing pydicom help [subcommand]. For example:

The pydicom command should automatically be available after you pip install pydicom. It should not require any updates to the system path or environment variables.

If you are helping develop pydicom code, and are using git clones, you will have to pip install -e . or python setup.py develop from the pydicom repository root. This has to be repeated for any changes to setup.py (e.g. to add a new subcommand).

If you are developing subcommands within your own package, you will need to reinstall your package similar to the above as you add entry points.

CLIs are useful for general exploration while programming, but also can be combined with other command-line filters for additional functionality. The following is an example of piping the output of the pydicom ‘show’ subcommand into ‘grep’, filtering for lines with either “Dose” or “Sequence” in them:

Using the “or Sequence” (`\|Sequence`) regular expression as above allows you to see any filtered results in relation to their parent Sequences.

See the pydicom show command section for more examples of the show command, its options, and the ability to show only data elements or sequences within the file.

The pydicom show command displays representation of DICOM files or parts of them from a command-line terminal.

Some examples were already given in the Introduction, but here we will show some additional options.

To see the available options, in a command-line terminal, type pydicom help show or pydicom show -h.

The basic command with no options shows all data elements and nested sequences:

Note that prefixing the file specification with pydicom:: will read the file from the pydicom test data files rather than from the file system.

You can also show just parts of the DICOM file by specifying a data element using the usual pydicom keyword notation:

The -q quiet argument shows a minimal version of some of the information in the file, using just the DICOM keyword and value (not showing the tag numbers and VR). The example below shows the quiet mode with an image slice:

And the following example shows an RT Plan in quiet mode:

Quiet modes always show the SOP Class UID, patient and study information as shown in the above two examples. After those elements, custom values for different SOP classes are shown. Currently “Image Storage” and “RT Plan Storage” classes have custom extra information. Please submit an issue on the pydicom issues list or a pull request to help us expand the list of custom ‘quiet’ mode SOP Classes.

The pydicom codify command takes a DICOM file and produces Python code to recreate that file, or, optionally a subset within that file.

See Using Codify for full details of writing a complete file. Here we will review the command-line options in more detail than in that section, and show how to export a dataset within a DICOM file that has sequences.

Warning

The code produced by codify will contain all the information in the original file, which may include private health information or other sensitive information.

A simple example of using the codify command would be:

Note that prefixing the file specification with pydicom:: will read the file from the pydicom test data files rather than from the file system.

In the above example, the output was directed to screen, because no output file was specified. To see the available command options, use the help command:

For example:

would read the DICOM file “dicomfile.dcm” and write the Python code to file “pythoncode.py”. In that code, near the end of the file would be a ds.save_as("savename.dcm", ...) line.

Note

By default, any private data elements within the file are not translated to code. If you want to include them, use the -p parameter.

Note that the filespec argument to the codify command, as for the show command, allows you to specify a data element within the file, rather than the whole file:

Currently, only a data element which is a Dataset (an item within a Sequence) is accepted. The resulting code would not on its own produce a correct DICOM file, but could be useful as a model when creating more complete code. For example, issuing code for one item in a Sequence could be the starting point towards a loop producing a number of sequence items.

Developers can create their own ‘subcommands’ for the pydicom command, by adding entry points to their package’s setup.py file, specifying a callback function to register the subcommand and its arguments.

If you wanted to create two subcommands, ‘command1’ and ‘command2’, your setup.py file should include something like:

The "pydicom_subcommands" is a literal string; this must not be changed or pydicom will not find your subcommand.

The add_subparser function name could be changed if you wish, but usually would be used by convention, and is assumed in the following examples.

In the module you have specified, create the add_subparser function, which takes a single argument subparsers, and a do_command function, which will take the call when you subcommand is actually used at the command line:

And define your command function:

The pydicom command uses Python’s argparse library to process commands.

The above code snippets show adding the filespec argument, and processing the resulting dataset-element_value pairs in the do_command() function. This is recommended if you wish to use the filespec as was seen in the pydicom show command and pydicom codify command sections. If not, you can just create a normal arg with the type set to argparse.FileType to open files yourself.

The above has been shown in relation to a different package than pydicom; however, if you think your command has general use, please consider contributing it to pydicom: in that case, change the entry points in the pydicom setup.py script, and add a module under pydicom.cli and create a pull request.